Banner

warning

This is the documentation for the Advanced API. Most developers should use our Simplified API (documented in Banner), which comes with several built-in features such as:

• Automatic ad loading
• Retries for failed requests
• Simplified lifecycle management

Only use the Advanced API if you need fine-grained control over the ad loading and presentation lifecycle.

The Advanced API provides direct access to individual Banner instances, giving you complete control over when and how ads are loaded and displayed.

Banner ads occupy a small portion of the user interface, either at the bottom or the top of the screen.

Once you create a Banner instance, you must use Load() to start loading. When loaded, banners are automatically added to the screen, so if this is not what you want you should use Hide(). This controls only its visibility, meaning that if the banner wasn't loaded yet it will continue to do so in background.

Use Show() when you need the banner to be displayed, indicating the position as explained below.

Finally, use Dispose() when you won't be using this banner instance anymore. That being said, we don't recommend disposing banners but reusing them instead. You can create one instance for each banner, and call Load() every time you need to make sure a new ad is available.

Create a Banner instance

var banner = Banner.Create("<placement-id>", position: Banner.Position.Bottom, size: Size.Phone);
banner.Hide(); // This prevents banner from automatically showing when loaded

Register ad callbacks

// Load Callbacks
banner.OnPrebiddingFinished += result => {
    Debug.Log("Banner client-side bidding finished!");
};

banner.OnLoaded += result => {
    Debug.Log("Banner loaded!");
};

banner.OnFailedToLoad += (error, result) => {
    Debug.Log($"Banner failed to load. Reason: {error.Message}");
};

// Impression Callback
banner.OnImpression += impressionData => {
    Debug.Log("Banner impression!");
};

info

For information about handling callback threads using XMediatorMainThreadDispatcher please refer to Sanitize Callback Threads.

Load an ad

// When the banner finishes loading, it will automatically be added to the view hierarchy
banner.Load();

Load an ad (with custom properties)

banner.Load(
    customProperties: new CustomProperties.Builder()
        .AddString("game_mode", "classic")
        .Build()
);

Hide a banner

banner.Hide();

Show and change a banner's position

// Optionally, set the ad space where the banner will be shown
banner.SetAdSpace("banner-ad-space")

// Change position to the top of the screen
banner.Show(Banner.Position.Top);

// Change position to bottom of the screen
banner.Show(Banner.Position.Bottom);

Dispose an ad

banner.Dispose();

Banner sizes

Constant	Size (WxH)	Description
Phone	320x50	Size for banners used in phone devices
Tablet	728x90	Size for banners used in tablet devices
MREC	300x250	Size for IAB Medium Rectangle banners

Size is in DP for Android and Points for iOS.

Banner position

Constant	Description
Top	Banner will be positioned at the top of the screen
Bottom	Banner will be positioned at the bottom of the screen

Banner autorefresh

After being displayed for some time, our banner fires a Load() call automatically to refresh its contents. You can configure this time through our Admin tool for each one of your banners.

Banner retry

Our banner has a built-in auto retry for failed load attempts. This means that when a banner fails to load, it will retry again until it loads successfully. Time between each retry attempt will increase using an exponential backoff. You should not add any retry logic on your end, as it may interfere with our retry behaviour.

Complete example

BannerTest.cs

using JetBrains.Annotations;
using UnityEngine;
using UnityEngine.UI;
using XMediator.Api;

namespace X3M.XMediatorTest.Scripts
{
    public class BannerTest : MonoBehaviour
    {
        public Button CreateButton;
        public Button LoadButton;
        public Button ShowBannerTopButton;
        public Button ShowBannerBottomButton;
        public Button HideBannerButton;

        [CanBeNull] private Banner _banner;
        private Banner.Position _position = Banner.Position.Bottom;

        private void Start()
        {
            CreateButton.onClick.AddListener(OnCreateClicked);
            LoadButton.onClick.AddListener(OnLoadClicked);
            ShowBannerTopButton.onClick.AddListener(OnShowBannerTopClicked);
            ShowBannerBottomButton.onClick.AddListener(OnShowBannerBottomClicked);
            HideBannerButton.onClick.AddListener(OnHideBannerClicked);
        }

        private void OnDestroy()
        {
            // Dispose the banner at the end of its lifecycle
            _banner?.Dispose();
        }

        private void OnCreateClicked()
        {
            Log("Create button clicked.");

            // Dispose previous banner instance
            _banner?.Dispose();

            // Create a banner instance
            _banner = Banner.Create("<placement-id>", position: _position);

            // Load Callbacks
            _banner.OnPrebiddingFinished += result => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Banner client-side bidding finished!"); }
            );

            _banner.OnLoaded += result => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log("Banner loaded!"); }
            );

            _banner.OnFailedToLoad += (error, result) => XMediatorMainThreadDispatcher.Enqueue(
                () => { Log($"Banner failed to load. Reason: {error.Message}"); }
            );

            // Impression Callback
            _banner.OnImpression += impressionData => { Log($"Banner impression!"); };
        }

        private void OnLoadClicked()
        {
            Log("Load button clicked.");
            _banner?.Load();
        }

        private void OnShowBannerTopClicked()
        {
            Log("Show banner top button clicked.");
            _position = Banner.Position.Top;
            _banner?.Show(_position);
        }

        private void OnShowBannerBottomClicked()
        {
            Log("Show banner bottom button clicked.");
            _position = Banner.Position.Bottom;
            _banner?.Show(_position);
        }

        private void OnHideBannerClicked()
        {
            Log("Hide banner button clicked.");
            _banner?.Hide();
        }

        private static void Log(string message)
        {
            Debug.Log($"[BannerTest] {message}");
        }
    }
}